---
title: Collaboration
icon: '#pro/CloudCheck'
---

<MetaData
  lang="en-US"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-docs-collaboration',
      locale: '@univerjs/preset-docs-collaboration/locales/en-US',
      style: '@univerjs/preset-docs-collaboration/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/collaboration',
    }, {
      client: '@univerjs-pro/collaboration-client',
      facade: '@univerjs-pro/collaboration-client/facade',
      locale: '@univerjs-pro/collaboration-client/locales/en-US',
    }, {
      client: '@univerjs-pro/collaboration-client-ui',
      facade: '@univerjs-pro/collaboration-client-ui/facade',
      style: '@univerjs-pro/collaboration-client-ui/lib/index.css',
    }],
    server: 'Yes',
  }}
/>

<Callout type="warning" title="Caution">
  The collaborative editing functionality requires support from the Univer server. Please ensure that you have correctly installed and configured the Univer server. For details, please refer to: [Upgrading to Pro](/guides/pro)
</Callout>

The collaborative editing feature allows multiple users to edit the same document simultaneously with real-time synchronization of changes. It is ideal for team collaboration and multi-user editing scenarios.

## Preset Mode

### Installation

<Callout>
  The `UniverDocsCollaborationPreset` preset from `@univerjs/preset-docs-collaboration` depends on the `UniverDocsDrawingPreset` and `UniverDocsAdvancedPreset` presets at runtime. Please install `@univerjs/preset-docs-drawing` and `@univerjs/preset-docs-advanced` first.
</Callout>

```package-install
npm install @univerjs/preset-docs-drawing @univerjs/preset-docs-advanced @univerjs/preset-docs-collaboration
```

### Usage

```typescript
import { UniverDocsAdvancedPreset } from '@univerjs/preset-docs-advanced' // [!code ++]
import UniverPresetDocsAdvancedEnUS from '@univerjs/preset-docs-advanced/locales/en-US' // [!code ++]
import { UniverDocsCollaborationPreset } from '@univerjs/preset-docs-collaboration' // [!code ++]
import UniverPresetDocsCollaborationEnUS from '@univerjs/preset-docs-collaboration/locales/en-US' // [!code ++]
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'
import { UniverDocsDrawingPreset } from '@univerjs/preset-docs-drawing' // [!code ++]
import UniverPresetDocsDrawingEnUS from '@univerjs/preset-docs-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/presets/lib/styles/preset-docs-core.css'
import '@univerjs/preset-docs-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-docs-advanced/lib/index.css' // [!code ++]
import '@univerjs/preset-docs-collaboration/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetDocsCoreEnUS,
      UniverPresetDocsDrawingEnUS, // [!code ++]
      UniverPresetDocsAdvancedEnUS, // [!code ++]
      UniverPresetDocsCollaborationEnUS, // [!code ++]
    ),
  },
  collaboration: true, // [!code ++]
  presets: [
    UniverDocsCorePreset(),
    UniverDocsDrawingPreset({ // [!code ++]
      collaboration: true, // [!code ++]
    }), // [!code ++]
    UniverDocsAdvancedPreset({ // [!code ++]
      collaboration: true, // [!code ++]
    }), // [!code ++]
    UniverDocsCollaborationPreset({ // [!code ++]
      universerEndpoint: 'http://localhost:3010', // [!code ++]
    }), // [!code ++]
  ],
})
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-preset-mode) for configuration.

{/* ### Presets and Configuration */}

## Plugin Mode

### Installation

```package-install
npm install @univerjs-pro/collaboration @univerjs-pro/collaboration-client @univerjs-pro/collaboration-client-ui
```

### Usage

```typescript
import { UniverCollaborationPlugin } from '@univerjs-pro/collaboration' // [!code ++]
import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client' // [!code ++]
import { BrowserCollaborationSocketService, UniverCollaborationClientUIPlugin } from '@univerjs-pro/collaboration-client-ui' // [!code ++]
import CollaborationClientEnUS from '@univerjs-pro/collaboration-client/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/collaboration-client/facade' // [!code ++]
import '@univerjs-pro/collaboration-client-ui/facade' // [!code ++]

import '@univerjs-pro/collaboration-client/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      CollaborationClientEnUS, // [!code ++]
    ),
  },
})

// By setting the override option to [[IAuthzIoService, null]], you can instruct Univer not to register the built-in IAuthzIoService.
// By setting the override option to [[IUndoRedoService, null]], you can instruct Univer not to register the built-in IUndoRedoService.
// This way, Univer will use the services provided by the UniverCollaborationPlugin as the implementation for the authorization and undo-redo features.
const univer = new Univer({
  override: [ // [!code ++]
    [IAuthzIoService, null], // [!code ++]
    [IUndoRedoService, null], // [!code ++]
  ], // [!code ++]
})

univer.registerPlugin(UniverCollaborationPlugin) // [!code ++]
univer.registerPlugin(UniverCollaborationClientPlugin, { // [!code ++]
  socketService: BrowserCollaborationSocketService, // [!code ++]
  authzUrl: 'http://localhost:3010/universer-api/authz', // [!code ++]
  snapshotServerUrl: 'http://localhost:3010/universer-api/snapshot', // [!code ++]
  collabSubmitChangesetUrl: 'http://localhost:3010/universer-api/comb', // [!code ++]
  collabWebSocketUrl: 'ws://localhost:3010/universer-api/comb/connect', // [!code ++]
}) // [!code ++]
univer.registerPlugin(UniverCollaborationClientUIPlugin) // [!code ++]
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-plugin-mode) for configuration.

{/* ### Plugins and Configuration */}

## Collaborative Document Data

The collaborative editing plugin relies on the Univer server, and the data for collaborative documents is stored in the Univer server.

### `unitId`

Each collaborative document in the Univer server has a unique `unitId`. The Univer collaboration client (collaborative editing plugin) uses the `unitId` to retrieve the corresponding collaborative document data from the Univer server for collaborative editing.

### `type`

`type` is the type of the collaborative document, which determines the initial data structure of the collaborative document.

## Creating Collaborative Documents

There are multiple ways to create collaborative documents in the Univer server:

- You can create a blank document using the [Create Document](/guides/pro/api#create-document) API.
- You can import a `.docx` file into the Univer server using the `FUniver.importDOCXToUnitIdAsync` method provided by the [Import Plugin](/guides/docs/features/import-export).

## Loading Collaborative Documents via URL Parameters

The `@univerjs-pro/collaboration-client` plugin provides functionality to automatically load the corresponding data based on the URL parameters `unit` and `type`, which can simplify data loading logic in some scenarios.

If you want to use this feature, you need to modify the existing data loading logic appropriately and add the `unit` and `type` parameters to the URL, as shown below:

```typescript
import { UniverInstanceType } from '@univerjs/core'
// In preset mode, `UniverInstanceType` can be imported from `@univerjs/presets`
import { UniverInstanceType } from '@univerjs/presets'

// The original logic, applicable to non-collaborative documents
univer.createUnit(UniverInstanceType.UNIVER_DOC, {}) // [!code --]

// The modified logic, applicable to collaborative documents
const url = new URL(window.location.href) // [!code ++]
const unit = url.searchParams.get('unit') // [!code ++]

if (unit) { // [!code ++]
  // If the URL contains the unit parameter, the data will be loaded automatically
} else { // [!code ++]
  // Or create a new document
  fetch(`/universer-api/snapshot/${UniverInstanceType.UNIVER_DOC}/unit/-/create`, { // [!code ++]
    method: 'POST', // [!code ++]
    headers: { // [!code ++]
      'Content-Type': 'application/json', // [!code ++]
    }, // [!code ++]
    body: JSON.stringify({ // [!code ++]
      type: UniverInstanceType.UNIVER_DOC, // instance type // [!code ++]
      name: 'New Doc By Univer', // doc name // [!code ++]
      creator: 'user', // creator name // [!code ++]
    }), // [!code ++]
  }).then((response) => { // [!code ++]
    if (!response.ok) { // [!code ++]
      throw new Error('create unit failed') // [!code ++]
    } // [!code ++]
    return response.json() // [!code ++]
  }).then((data) => { // [!code ++]
    if (!data.unitID) { // [!code ++]
      throw new Error('create unit failed') // [!code ++]
    } // [!code ++]
    url.searchParams.set('unit', data.unitID) // [!code ++]
    url.searchParams.set('type', String(UniverInstanceType.UNIVER_DOC)) // [!code ++]
    window.location.href = url.toString() // [!code ++]
  }).catch((error) => { // [!code ++]
    console.error(error) // [!code ++]
  }) // [!code ++]
} // [!code ++]
```

## Facade API

### Loading Collaborative Documents

If you do not want to use URL parameters to load collaborative documents, you can also load collaborative documents through the Facade API.

```typescript
const collaboration = univerAPI.getCollaboration()
const workbook = await collaboration.loadSheetAsync('your-unit-id')
```

## Further Reading

If you want to learn more about how collaborative editing works, you can read the following article:

- [OT Algorithm and Univer’s Collaborative Editing Design](/blog/ot)
